home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / AmigaSystem / AmiStart / ModulesSDK.lha / developer.doc next >
Text File  |  2002-04-27  |  13KB  |  331 lines
  1. Amistart Module Developer Documentation:
  2.  
  3. This documentation describes how to implement external AmiStart modules, the
  4. AmiStart module developer kit bases on "Lib37x" available on AMINET done by
  5. Andreas R. Kleinert. This means you could spread module-libraries but you can't
  6. spread the sourcecode of them without asking Andreas R. Kleinert for permission
  7.  
  8.  
  9. What are Modules?
  10.  
  11. modules have a library equal structure, all modules with the same Version must
  12. implement all Functions for this Version.
  13. Modules makes able to add Features to AmiStart, like a WindowList Display,
  14. TaskDisplay and much more.
  15. AmiStart calls the defined function to get informations what to display and how to
  16. do this.
  17. You cannot call AmiStart functions!, your module is only a information server and AmiStart is the
  18. client.
  19.  
  20. How to start?
  21.  
  22. First think about what version of a Module you really need, see the Version
  23. Module Description below for example if you only need Version 39 Functions
  24. set VERSION in the File LibInit.c to 39 (all modules must at least have
  25. Version 39, coz this is the initial Version). Unsing a Version prevents AmiStart
  26. from calling Functions of upper Versions, but all Functions must be implement
  27. for this Version and all of its parent.
  28. Change the EXLIBNAME, REVISION and Copyright notice in LibInit.c.
  29. Implement all Module Functions for your specific Version in the File ModuleFuncs.c
  30. Finally compile StartUp.c LibInit.c and ModuleFuncs.c link them in this order without
  31. any StartUp Code (library linking) and finnaly link the amiga.lib, name the output
  32. "modulename".module, where modulename is the same name as defined in libInit.c named
  33. EXLIBNAME.
  34.  
  35. NOTE: i have only tested the makefile for the vbcc compiler and can not give any guarantee that other
  36. makefiles will work.
  37.  
  38. The resulting module must be copied to modules in the AmiStart Directory, or in a
  39. Directory modules inside the DATAPATH defined by the DATAPATH TOOLTYPE.
  40.  
  41. How a Module Works.
  42.  
  43. A Module doesn't have any specific data structures you are free to implement your
  44. data as you need it, all requests will be done by specific Functions with fixed
  45. Parameters and Fixed results, this functions must be implement.
  46.  
  47.  
  48. ******************************************************************************************
  49. ******************************************************************************************
  50.  
  51.  
  52. Which Functions must be implement?
  53.  
  54. Note: Newer Versions must implement previous Version Functions.
  55. Note: a module is library based, so you must make all functions reentrant.
  56.  
  57. A Function has the following Structure:
  58.  
  59.     RETURNTYPE FunctionName(PAREMETER1, PARAMETER2, ...)
  60.  
  61.     while PARAMETERS are all filled by AmiStart,
  62.  
  63. ******************************************************************************************
  64.  
  65. Version 39: (initial Version)
  66.  
  67.     APTR OpenModule()
  68.  
  69.         Initial a Module.
  70.  
  71.         INPUTS: none
  72.         OUTPUT: APTR, if NULL initialation fails and module will not be used even if the module is loaded.
  73.                 after quitting AmiStart, this value will be passed to CloseModule even if it is NULL.
  74.                 This value will not be used by AmiStart, it will only passed to CloseModule(), and tested
  75.                 against NULL.
  76.  
  77.         Description:
  78.             AmiStart calls this command after you start AmiStart, it will be only called once so you
  79.             can (but you must not) do some initial/global setup like patches open libs and so on.
  80.  
  81.             Return non-NULL to make sure that AmiStart could use this Module, save allocated data somewhere inside
  82.             the returned data struct.
  83.  
  84.  
  85.         See: CloseModule()
  86.  
  87.     VOID CloseModule(APTR init = REG(a0))
  88.  
  89.         Opposit of OpenModule().
  90.  
  91.         INPUTS: init, returnstatement from OpenModule.
  92.         OUTPUT: none
  93.  
  94.         Description:
  95.             will be finnaly called once if the User quits AmiStart.
  96.             Be sure to make this Function "call save", coz it will be called
  97.             even if OpenModule() fails.
  98.             Do some cleanup here for example closing libs you have opened in OpenModule().
  99.  
  100.         See: OpenModule()
  101.  
  102.     STRPTR GetModuleInfo()
  103.  
  104.         Get a short info string for this Module.
  105.  
  106.         INPUTS: none
  107.         OUTPUT: STRPTR a pointer to a Module Info String.
  108.  
  109.         Description:
  110.             AmiStart calls this function to get a short Info Text, don't use newline characters here.
  111.             You can use MUI escape sequences.
  112.  
  113.         See: GetModuleDescription()
  114.  
  115.     STRPTR GetModuleDescription()
  116.  
  117.         Get a detailed Module description.
  118.  
  119.         INPUTS: none
  120.         OUTPUT: STRPTR a pointer to a Module Description String.
  121.  
  122.         Description:
  123.             AmiStart calls this function to get a detailed module description.
  124.             use any MUI esc sequenced and you can use linefeeds here.
  125.  
  126.         See: GetModuleInfo()
  127.  
  128.     APTR InitModule(struct RDArgs args = REG(a0), APTR pool = REG(a1))
  129.  
  130.         subinstallation of a module.
  131.  
  132.         INPUTS: rdArgs  Pointer to a dos RDArgs structure.
  133.                 pool    A Pointer to a exec memory pool the module could use to prevent memory fragmantation, you could
  134.                         use AllocVec/AllocMen instead.
  135.                         Memory flags are MEMF_ANY|MEMF_CLEAR, so you can be sure to get memory filled with zero bytes.
  136.         OUTPUT: APTR    module specific data,
  137.  
  138.         Description:
  139.             Once AmiStart is loaded and a Module is initialized by OpenModule(), AmiStart calls this Function
  140.             each time a user hits an entry this module belongs to (not the content of the entry), AmiStart indicates
  141.             here that AmiStart want to open A new Window and says i want to ask what i should display.
  142.             Displaying most system-structures needs to be read inside a Forbid()/Permit() call, you can
  143.             use this Function to get this information.
  144.             Return a pointer to a struct or something else, this Data will be used to get Infos what to display and
  145.             will be passed to DataRetieving functions.
  146.             The rdArgs argument is a dos RDArgs structure which can be used by dos/ReadArgs to parse the user settings string
  147.             which could be entered in the item settings window in AmiStart.
  148.             Don't use FreeArgs (AmiStart does this) and you can be sure, this Pointer is never NULL.
  149.             Note: the rdArgs pointer is only valid in InitModule().
  150.             Note: Use dos/ReadArgs() to parse Arguments in a dos like way "SWITCH/S,NUMBER/N=,....", see there.
  151.  
  152.             see the demo source.
  153.  
  154.             you can also generate a list "on the fly" inside the specific functions if it is sure
  155.             that other tasks do not destroy infos you want to get.
  156.  
  157.             the whole process for retrieving data done by AmiStart is.
  158.  
  159.                 APTR data = InitModule(args, pool);
  160.  
  161.                 while(NextModuleData(data)) {
  162.                     name = getModuleName(data);
  163.                     ...
  164.                 }
  165.                 DisposeModule(data, pool);
  166.  
  167.         NOTE:   you have to handle return values inside DisposeModule(), NextModuleData() ... AmiStart doesn't use this value
  168.                 it's only a "identifier" so your module can find out who has asked something.
  169.  
  170.         See: DisposeModule()
  171.  
  172.     void DisposeModule(APTR dat = REG(a0), APTR pool = REG(a1))
  173.  
  174.         opposite of InitModule()
  175.  
  176.         INPUTS: dat     return value from InitModule()
  177.                 pool    Pointer to a memory pool, so you can free Memory allocated in InitModule()
  178.  
  179.         Descrption:
  180.                 cleanup all allocations done by InitModule().
  181.                 this function will be called after the user closes the Window where moduledata is displayed.
  182.  
  183.         See: InitModule()
  184.  
  185.     BOOL NextModuleData(APTR data = REG(a0))
  186.  
  187.         set pointer
  188.  
  189.         INPUTS: data    returnstatement from InitModule()
  190.         OUTPUT: BOOL    if TRUE new data is available, else AmiStart stops getting more data.
  191.  
  192.         Description:
  193.             set a internal module pointer to the next data, so data retrieving functions are able
  194.             to return the next data. After InitModule() this function must set the pointer to the first vaild
  195.             data, so a simple loop could run through the whole list.
  196.  
  197.     STRPTR GetModuleName(APTR data = REG(a0))
  198.  
  199.         get name of actual item
  200.  
  201.         INPUTS: data    returnstatement form InitModule()
  202.         OUTPUT: STRPTR  String which will be displayed in a AmiStart Layer list.
  203.  
  204.         Description:
  205.             After NextModuleData() is called, this function should return the String which
  206.             will be displayed in an AmiStart Layer.
  207.  
  208.         Note:   data will be duplicated by AmiStart.
  209.  
  210.         See: GetModuleIcon(), GetModuleTool(), GetModuleUserData()
  211.  
  212.     STRPTR GetModuleIcon(APTR data = REG(a0))
  213.  
  214.         get icon of actual item
  215.  
  216.         INPUTS: data    returnstatement from InitModule()
  217.         OUTPUT: STRPTR  name of the Icon to display (leave ".info" extension).
  218.  
  219.         Description:
  220.             After NextModuleData() is called, this function should return the Name of the icon which
  221.             will be displayed in an AmiStart Layer. Should be modules/"modulename" by default
  222.  
  223.         Note:   data will be duplicated by AmiStart.
  224.  
  225.         See: GetModuleName(), GetModuleTool(), GetModuleUserData()
  226.  
  227.     STRPTR GetModuleTool(APTR data = REG(a0))
  228.  
  229.         get something from actual item
  230.  
  231.         INPUTS: data    returnstatement form InitModule()
  232.         OUTPUT: STRPTR  module specific String (not used in V39).
  233.  
  234.         Note:   data will be copied by AmiStart
  235.  
  236.         Description:
  237.             After NextModuleData() is called this, function should return something or NULL,
  238.             not used in V39, so you should!!!! return NULL in Ver. 39.
  239.  
  240.         See: GetModuleIcon(), GetModuleTool(), GetModuleUserData()
  241.  
  242.     ULONG GetModuleUserData(APTR data = REG(a0))
  243.  
  244.         get userdata from actual item
  245.  
  246.         INPUTS: data    returnstatement from InitModule()
  247.         OUTPUT: ULONG   an Item ID, for internal module usage.
  248.  
  249.         Description:
  250.             After NextModuleData() is called, this function should return the Item ID which will be
  251.             passed to some Functions to identify items which are selected.
  252.  
  253.         See: GetModuleIcon(), GetModuleTool(), GetModuleUserData(), DoModuleCommand(), HitModule()
  254.  
  255.     ULONG DoModuleCommand(APTR data = REG(a0), ULONG userdata = REG(d0))
  256.  
  257.         do a command for item with the ID userdata
  258.  
  259.         INPUTS: data        returnstatement from InitModule()
  260.                 userdata    a item identifier
  261.         OUTPUT: ULONG       0 = keep window alive, 1 = close window after doing this command
  262.                             upper Versions could return other VALUES.
  263.  
  264.         Description:
  265.             It the user klicks a item with the mouse this Function will be called, for example
  266.             a closewindow module could close a selected window here.
  267.             you can identify which item is clicked by userdata.
  268.  
  269.         See: HitModule()
  270.  
  271.     void HitModule(APTR data = REG(a0), ULONG userdata = REG(d0))
  272.  
  273.         do a hit command for item with the ID userdata
  274.  
  275.         INPUTS: data        returnstatement from InitModule()
  276.                 userdata    a item identifier
  277.         OUTPUT: none
  278.  
  279.         Description:
  280.             It the user enters the item range with the mouse this Function will be called, for example
  281.             a windowtofront module could bring a selected window to front here.
  282.             you can identify which item is clicked by userdata.
  283.  
  284.         NOTE:
  285.             moving the mouse over a item will not call this function again.
  286.  
  287.         See: DoModuleCommand()
  288.  
  289.     ULONG GetModuleFlags(APTR data = REG(a0))
  290.  
  291.         get Flags for actual item
  292.  
  293.         INPUTS: data        returnstatement from InitModule()
  294.         OUTPUT: ULONG       version 39 Modules should always return 0, others see definitions below
  295.  
  296.         Description:
  297.             AmiStart calls this method to retrive flags for actual requested Entry (set by NextModuleData),
  298.             in V39 this always should be ZERO, newer versions could have subdir Flags or others.
  299.  
  300.         See:    GetSpecialInfo(), GetModuleConfig()
  301.  
  302.     APTR GetSpecialInfo(APTR data = REG(a0))
  303.  
  304.         get special info for actual entry
  305.  
  306.         INPUTS: data        returnstatement from InitModule()
  307.         OUTPUT: APTR        pointer to special info for actual data, should always be NULL in V39
  308.  
  309.         Description:
  310.             Flag dependent special info (not used in V39).
  311.  
  312.         See:    GetModuleFlags(), GetModuleConfig()
  313.  
  314.     STRPTR GetModuleConfig(APTR data = REG(a0))
  315.  
  316.         get config string for actual entry, not used in V39
  317.  
  318.         INPUTS: data        returnstatement from InitModule()
  319.         OUTPUT: STRPTR      config string for actual entry, should always be NULL in V39
  320.  
  321.         Description:
  322.             AmiStart calls this method to get the config string for this entry, this could be used in newer
  323.             versions to pass configuration data to other modules, or creating subentrys throught the same module.
  324.  
  325.         See:    GetModuleFlags(), GetSpecialInfo()
  326.  
  327.  
  328.  
  329. *************************************************************************************
  330.  
  331. Version 40: (not yet defined)